Even before the term API (Application Programming Interface) became well-known, developers exchanged information in the form of data. This worked in a few different ways, like using defined interfaces in order to use a direct electronic path. Changes weren’t welcome, and many commonly said that “interfaces are carved in stone”.

This article series will prove that API management has become significantly more important in a network-oriented world. We’ll help point out ways to meet this requirement.

Is There a World Without Interfaces?

Of course, the question is purely rhetorical, because wherever we look, we find interfaces in many different forms. The best-known interface definition is the one for electrical devices. They must meet a certain specification so that they can consume electricity in order to function at all. They must also meet the specification for plugs so that they can be connected to a standardized socket. This combination has become normal in our daily lives and we use it without thinking about it much. And yet, this type of communication is based on a previously made agreement about a specification. This alone isn’t enough for success or gaining broad acceptance. What matters above all is trust and reliability. These two qualities have a high economic value. Device manufacturers trust that electricity providers reliably supply power through sockets and via the specified plug type. Electricity providers trust that device manufacturers won’t draw more voltage and/or current than directed in the specification for the defined socket type. And that works without problems, doesn’t it?

Back to IT

Here, things are exactly the same. We live from collecting data, analyzing it, modifying it, calculating it, and storing it. It’s also important to be able to exchange it with others— ideally both for the benefit of our business goals and the goals of our connected consumers.

In this environment, the same quality principles of trust and reliability apply as assumed for device manufacturers and electricity providers.

What is an API?

What distinguishes an Application Programming Interface (API) from a simple interface? If we consult the internet to answer this question, there are many definitions. Here are a few excerpts:

• “APIs (Application Programming Interfaces) consist of multiple definitions and protocols for developing and integrating application software. An API is an interface that allows independent applications to communicate and exchange data.”
• “APIs are mechanisms that enable two software components to communicate with each other via a set of definitions and protocols …”
• “An Application Programming Interface (API) is a set of defined rules for communication between different applications. It acts as an intermediary layer and, as such, processes data transfers between systems. In this way, companies can make their application data and functionality accessible to external developers, business partners, and also internal departments within their respective organizations.”

These sources are largely in agreement: it’s about a connection between two systems in order to communicate with each other. Yes, that’s almost it.

APIs describe the manner (see: socket design, current, voltage) of communication so that other systems (applications) can use their functionalities or data. For this to work, the definition must be converted into program code and a functioning interface (plug) must be created from it.

Interestingly, this can be done independently by each participant for their own context (programming language, framework). Thus, it’s not important for developers to know how an API is implemented. They simply use the defined interface in their environment.

What Are We Talking About?

There are many kinds of different APIs. There are specifications that allow access to databases or, more generally, to hard disks. Some APIs make it possible to create components for graphical user interfaces (for example, Microsoft’s Windows Application Programming Interface) In this series, we’ll primarily consider “HTTP APIs,” also often referred to as web services.

Now some readers may ask: “Why? It’s not that hard to formulate APIs. Plenty of tools support this. Extensions and changes aren’t a problem either because we know all of the users.”

We can easily imagine these statements because APIs are usually created for internal use. But since Google Maps, we also know that this can change very quickly. Suddenly, the API is available on the web and it becomes more difficult to know one’s users.

This scenario is becoming increasingly important as companies have realized that APIs can be monetized. This isn’t the only reason that good design is necessary. Interfaces have gained importance within companies. With the trend toward microservices, more teams have their own service and changes to interfaces involve more effort for consumers as well as provider teams than they did in the past.

From a business perspective, they’ve become more relevant as cost and effort drivers. Changes to APIs are a magnifying glass for the relationships between teams and the business responsibilities they represent. The business, social, and technical level is often relevant in order to know the correct response when two consumers have different requirements for an existing API.

Platform APIs vs. Service APIs

In most cases, APIs are used to exchange information (data). There are two models that ensure a user can consume information, but in different forms and with different motivations.

Platform APIs

Also called data APIs, these are closer to data organization and management, and are modeled accordingly. Platform APIs are characterized by the fact that they represent generic interfaces for reusing multiple services with similar data sets. This model is often seen as the base layer for an API ecosystem.

If we adopt this perspective, one could also say that they represent the first representation. Transformations are usually required for use.

Service APIs

Service APIs (or business APIs) are used to present specific data. For this purpose, they can use aggregated or composite representations of data from platform APIs. They have additional data processing to cover a specific requirement (use cases).

Core Question: Do I Actually Know My Stakeholders?

Both models are very different and have different motivations—keyword: “stakeholder management.” Regardless of whether customers can be asked directly, if assumptions must be made, or user behavior analyzed, knowing your stakeholders is worthwhile.

In design, there’s a reason that people say “form follows function”. The following guiding questions help us understand customers:

• Why is the API needed?
• Who should call it or program against it?
• What information is interesting for consumers?
• How frequently or extensively can the API be used?

How exactly an API is derived and what pitfalls should be considered will be addressed in the second part of this series.

And Then There’s The Reality

No matter how much caution, dedication, and passion went into modeling an API, consumers can have a completely different view. Some may say, “the customer is always right in matters of taste”, but that isn’t always true.

An API’s success doesn’t solely depend on its technical design, but on many other factors too. Anyone who knows the concept of switching costs from business administration knows that people adapt quickly. So what are the other factors?

Context

If consumers operate in the same or a similar context, the probability is high—perhaps even very high—that they’ll have a similar view of things and accept an API design determined by the context.

Environment

This behaves similarly to context if the environment is equated with industry-typical solutions. But it already gets harder when the consumer comes from a different environment (industry) and needs the API for their business success.

Market Power and/or Dependency

This is the extended version of the environment, along the lines of “consumers will follow me; they have no alternative.”

Free or Paid

This aspect can shift the prerequisites about if a habitation effect occurs or not. Those who pay for an API are more likely to want a say in its design and further development than if it was free to use. And yet, we providers have a strong interest in designing our API cleanly. These two quotes support our point:

• “APIs are forever” (Werner Vogels, Amazon)
• “An API should not be strictly coupled to the architecture of the backend” (Daniel Kocot, codecentric)

Both statements, from different perspectives, have something to do with customer perspective and customer retention. Consumers usually operate in their environment, with their own problems and requirements. They aren’t very interested in an API’s design weakness or the necessary changes behind APIs on offer. There’s a willingness to accept a somewhat clunky API. But a willingness to accept constant changes, even without a visible customer benefit? There’s significantly less of that. In the worst case, you offer a clunky API that cannot be changed because it has paying users. But you also cannot create a second, better API if it’s tied to the backend’s technology. It’s questionable whether new users can be won over with a clunky API.

The way out of this situation is costly, involves painful architectural or business decisions, and is also risky. We already see that APIs can be a real minefield, either internally or externally. They’re more than just a simple interface that can be programmed against.

They depend on many things, which is why API design can appear quite complex. And sometimes it is. In the following articles we will address a few aspects directly and show how to deal with them and potentially defuse them.